home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Over 1,000 Windows 95 Programs
/
Over 1000 Windows 95 Programs (Microforum) (Disc 1).iso
/
1271
/
wsc4vb_r.doc
< prev
next >
Wrap
Text File
|
1997-03-19
|
45KB
|
1,383 lines
Windows Standard Communications
Library for Visual Basic
(WSC4VB)
REFERENCE MANUAL
Version 2.0
March 15, 1997
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1996-1997
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 205-881-4630
FAX : 205|880|0925
BBS : 205-880-9748
email : info@marshallsoft.com
web : www.marshallsoft.com
_______
____|__ | (R)
--+ | +-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
--+--+ | +---------------------
|___|___| MEMBER
MARSHALLSOFT is a trademark of MarshallSoft Computing, Inc.
WSC4VB Reference Manual Page 1
C O N T E N T S
Chapter Page
Table of Contents.............................2
WSC Functions.................................4
SioBaud....................................4
SioBrkSig..................................4
SioCTS.....................................5
SioDCD.....................................5
SioDone....................................6
SioDSR.....................................6
SioDTR.....................................7
SioFlow....................................7
SioGetc....................................8
SioGets....................................8
SioInfo....................................9
SioParms...................................9
SioPutc...................................10
SioPuts...................................10
SioReset..................................11
SioRI.....................................11
SioRTS....................................12
SioRxClear................................12
SioRxQue..................................13
SioStatus.................................13
SioTxClear................................14
SioTxQue..................................14
SioUnGetc.................................15
WSC Error Codes..............................15
WSC4VB Reference Manual Page 2
C O N T E N T S
(continued)
Chapter Page
Modem I/O Functions..........................16
mioBreak..................................16
mioDriver.................................16
mioQuiet..................................17
mioResult.................................17
mioSendTo.................................18
mioWaitFor................................18
XYDRIVER Functions...........................19
xyAbort...................................19
xyAcquire.................................19
xyDebug...................................20
xyDriver..................................20
xyGetMessage..............................21
xyGetParameter............................21
xyRelease.................................22
xyStartRx.................................22
xyStartTx.................................23
XYDRIVER Error Codes.........................23
NOTE: DefInt is assumed for all functions in the Win16 library while
DefLng is asumed for all functions in the Win32 library. Also note
that all arguments are passed by value except for strings.
WSC4VB Reference Manual Page 3
+-------------+-----------------------------------------------------+
| SioBaud | Sets the baud rate. |
+-------------+-----------------------------------------------------+
Syntax Function SioBaud(ByVal Port, ByVal BaudCode)
' Port : Port selected.
' BaudCode : Baud code or actual baud rate.
Remark The SioBaud Function sets the baud rate without resetting
the port. It is used to change the baud rate after calling
SioReset.
SioBaud may be called with either the actual baud rate value
or one of the baud rate codes as follows:
Code Rate Name Code Rate Name
0 300 Baud300 5 9600 Baud9600
1 600 Baud600 6 19200 Baud19200
2 1200 Baud1200 7 38400 Baud38400
3 2400 Baud2400 8 57600 Baud57600
4 4800 Baud4800 9 115200 Baud115200
Return IE_BADID : No such port.
IE_BAUDRATE : Unsupported baud rate.
Other See SioReset.
+-------------+-----------------------------------------------------+
| SioBrkSig | Asserts, cancels, or detects BREAK signal. |
+-------------+-----------------------------------------------------+
Syntax Function SioBrkSig(ByVal PortCmd)
' Port : Port selected.
' Cmd : ASSERT, CANCEL, or DETECT.
Remark The SioBrkSig Function controls the BREAK bit in the line
status register. The legal commands are:
ASSERT_BREAK : 'A' to assert BREAK
CANCEL_BREAK : 'C' to cancel BREAK
DETECT_BREAK : 'D' to detect BREAK
ASSERT_BREAK, CANCEL_BREAK, and DETECT_BREAK are defined in
WSC4VB.PAS. See MODEM.C for an example of the use of SioBrkSig.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
WSC_RANGE : Illegal command. Expected 'A', 'C', or 'D'.
>0 : BREAK signal detected (DETECT command only)
Other See SioBrkKey.
WSC4VB Reference Manual Page 4
+-------------+-----------------------------------------------------+
| SioCTS | Reads the Clear to Send (CTS) modem status bit. |
+-------------+-----------------------------------------------------+
Syntax Function SioCTS(ByVal Port)
' Port : Port selected.
Remark The SioCTS Function is used to detect if CTS (Clear To Send)
is set (1) or clear (0). Some Windows Win16 COMM drivers
cannot read the CTS bit correctly!
The CTS line is used by some error correcting modems to
implement hardware flow control. CTS is dropped by the modem
to signal the computer not to send data and is raised to
signal the computer to continue.
Refer to the User's Manual for a discussion of flow control.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
0 : CTS has not changed.
>0 : CTS has changed.
Other See SioFlow, SioDSR, SioRI, SioDCD, and SioModem.
+-------------+-----------------------------------------------------+
| SioDCD | Reads the Data Carrier Detect (DCD) modem staus bit|
+-------------+-----------------------------------------------------+
Syntax Function SioDCD(ByVal Port)
' Port : Port selected.
Remark The SioDCD Function is used to read the Data Carrier Detect
(DCD) modem status bit. Also see SioModem.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
0 : DCD is clear.
>0 : DCD is set.
Other See SioDSR, SioCTS, SioRI, and SioModem.
WSC4VB Reference Manual Page 5
+-------------+-----------------------------------------------------+
| SioDone | Terminates further serial processing. |
+-------------+-----------------------------------------------------+
Syntax Function SioDone(ByVal Port)
' Port : Port selected.
Remark The SioDone Function terminates further serial processing,
allowing other applications to use the port.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
Other See SioReset.
+-------------+-----------------------------------------------------+
| SioDSR | Reads the Data Set Ready (DSR) modem status bit. |
+-------------+-----------------------------------------------------+
Syntax Function SioDSR(ByVal Port)
' Port : Port selected.
Remark The SioDSR Function is used to detect if DSR (Data Set Ready)
is set (1) or clear (0). Some Windows Win16 COMM drivers
cannot read the DSR bit correctly!
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
0 : DSR has not changed.
>0 : DSR has changed.
Other See SioCTS, SioRI, and SioDCD.
WSC4VB Reference Manual Page 6
+-------------+-----------------------------------------------------+
| SioDTR | Set, clear, or read Data Terminal Ready (DTR). |
+-------------+-----------------------------------------------------+
Syntax Function SioDTR(ByVal PortCmd)
' Port : Port selected.
' Cmd : DTR command (see below).
Remark The SioDTR Function controls the Data Terminal Ready (DTR) bit
in the modem control register. DTR should always be set when
communicating with a modem. Commands (defined in WSC4VB.PAS):
SET_LINE : 'S' to set DTR (ON)
CLEAR_LINE : 'C' to clear DTR (OFF)
READ_LINE : 'R' to read DTR
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
WSC_RANGE : Not one of 'S', 'C', or 'R'.
0 : DTR is OFF (READ_LINE Command).
>0 : DTR is ON (READ_LINE Command).
Other See SioRTS.
+------------+------------------------------------------------------+
| SioFlow | Sets flow control. |
+------------+------------------------------------------------------+
Syntax Function SioFlow(ByVal PortCmd)
' Port : Port selected.
' Cmd : Class of flow control (see below).
Remark The SioFlow Function is used to enable or disable hardware
flow control. Hardware flow control uses RTS and CTS to
control data flow between the modem and the computer. To
enable flow control, call SioFlow with Cmd set to:
Cmd Flow Control
'H' Hardware (RTS/CTS) flow control.
'S' Software (XON/XOFF) flow control.
'N' No flow control.
In order for hardware flow control to work correctly, your
modem must also be configured to work with hardware flow
control, and your computer to modem cable must have RTS and
CTS wired straight through. If you enable hardware flow
control, do not modify the RTS line (by calling SioRTS). Flow
control is disabled after resetting a port.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
WSC_RANGE : Cannot recognize Cmd.
-1 : Flow control disabled.
>0 : Flow control enabled.
Other See SioPutc
WSC4VB Reference Manual Page 7
+------------+------------------------------------------------------+
| SioGetc | Reads the next character from the serial line. |
+------------+------------------------------------------------------+
Syntax Function SioGetc(ByVal Port)
' Port : Port selected.
Remark The SioGetc Function reads a byte from the selected serial
port. WSC_NO_DATA (-100) is returned if no byte is available.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
WSC_NO_DATA : If timed out (no data available).
>= 0 : Character read.
Other See SioUnGetc and SioGets.
+------------+------------------------------------------------------+
| SioGets | Reads the next byte buffer from the serial line. |
+------------+------------------------------------------------------+
Syntax Function SioGetc(ByVal Port, Buffer As String, ByVal Cnt)
' Port : Port selected.
' Buffer : Receive buffer.
' Cnt : Number bytes wanted.
Remark The SioGets Function reads the smaller of the number of bytes
wanted (Cnt) and the number of bytes in the receive buffer. A
zero is return if no bytes are read.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
>= 0 : Number of characters actually read.
Other See SioUnGetc and SioPutc.
WSC4VB Reference Manual Page 8
+-------------+-----------------------------------------------------+
| SioInfo | Returns WSC4VB library information. |
+-------------+-----------------------------------------------------+
Syntax Function SioInfo(ByVal Cmd)
' Cmd : Command (See below).
Remark The SioInfo Function returns an integer code corresponding to
the Cmd as follows.
Command SioInfo returns
'V' Library version number.
Return See remarks above.
-1 : Cannot recognize Cmd.
+-------------+-----------------------------------------------------+
| SioParms | Sets parity, stop bits, and word length. |
+-------------+-----------------------------------------------------+
Syntax Function SioParms(ByVal Port, ByVal Parity,
ByVal StopBits, ByVal DataBits)
' Port : Port selected.
' Parity : Parity code [0,1,2].
' StopBits : Stop bits code [0,1].
' DataBits : Word length code [0,1,2,3].
Remark The SioParms Function sets the parity, stop bits, and word
length. If the default parity (none), stop bits (1), or word
length (8) is not acceptable, then they can be changed by
calling SioParms. SioParms can be called either before or
after calling SioReset. See file WSC4VB.PAS.
Use the constant values defined in WSC4VB.PAS to minimize the
chance of passing an incorrect parameter value.
Parity : NoParity, OddParity, EvenParity.
StopBits : OneStopBit, TwoStopBits.
DataBits : WordLength7, WorldLength8.
Return IE_BADID : No such port.
IE_BYTESIZE : Word length not supported.
WSC_RANGE : Parameter out of range.
Other See SioReset.
WSC4VB Reference Manual Page 9
+-------------+-----------------------------------------------------+
| SioPutc | Transmit a character over a serial line. |
+-------------+-----------------------------------------------------+
Syntax Function SioPutc(ByVal PortCh)
' Port : Port selected.
' Ch : Character to send.
Remark The SioPutc Function copies the character to the transmit
queue for subsequent transmission.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
0 : No error.
Other See SioGetc and SioFlow.
+-------------+-----------------------------------------------------+
| SioPuts | Transmits a byte buffer over a serial line. |
+-------------+-----------------------------------------------------+
Syntax Function SioPuts(ByVal Port, Buffer As String, ByVal Cnt)
' Port : Port selected.
' Buffer : String of bytes to transmit.
Remark The SioPuts Function copies the characters to the transmit
queue for subsequent transmission.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
>= 0 : The number of bytes actually transmitted.
Other See SioGetc and SioFlow.
WSC4VB Reference Manual Page 10
+-------------+-----------------------------------------------------+
| SioReset | Initialize a serial port for processing. |
+-------------+-----------------------------------------------------+
Syntax Function SioReset(ByVal Port,
ByVal RxQueSize,ByVal TxQueSize)
' Port : Port selected.
' RxQueSize : Receive queue size.
' TxQueSize : Transmit queue size.
Remark The SioReset Function initializes the selected serial port.
SioReset should be called before making any other calls to
WSC4VB. SioReset uses the parity, stop bits, and word length
value previously set if SioParm was called, otherwise the
default values (see SioParm) are used.
Return IE_BADID : No such port.
IE_OPEN : Already open.
IE_MEMORY : Cannot allocate memory.
IE_HARDWARE : Hardware error.
Other See SioBaud, SioParms, and SioDone.
+-------------+-----------------------------------------------------+
| SioRI | Reads the Ring Indicator (RI) modem status bit. |
+-------------+-----------------------------------------------------+
Syntax Function SioRI(ByVal Port)
' Port : Port selected.
Remark The SioRI Function is used to read the Ring Indicator (RI)
modem status bit.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
0 : RI is clear.
>0 : RI is set (RING has occurred).
Other See SioDSR, SioCTS, and SioDCD.
WSC4VB Reference Manual Page 11
+-------------+-----------------------------------------------------+
| SioRTS | Sets, clears, or reads the Request to Send (RTS). |
+-------------+-----------------------------------------------------+
Syntax Function SioRTS(ByVal PortCmd)
' Port : Port selected.
' Cmd : RTS command (SET, CLEAR, or READ).
Remark The SioRTS Function controls the Request to Send (RTS bit in
the modem control register.
The RTS line is used by some error correcting modems to
implement hardware flow control. RTS is dropped by the
computer to signal the modem not to send data, and is raised
to signal the modem to continue. RTS should be set when
communicating with a modem unless Flow Control is being used.
Refer to the User's Manual for a discussion of flow control.
Commands (defined in WSC4VB.PAS) are:
SET_LINE 'S' : set RTS (ON)
CLEAR_LINE 'C' : clear RTS (OFF)
READ_LINE 'R' : read RTS
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
WSC_RANGE : Command is not one of 'S', 'C', or 'R'.
0 : RTS is OFF ('R' command).
>0 : RTS is ON ('R' command).
Other See SioFlow and SioDTR.
+------------+------------------------------------------------------+
| SioRxClear | Clears the receive buffer. |
+------------+------------------------------------------------------+
Syntax Function SioRxClear(ByVal Port)
' Port : Port selected.
Remark The SioRxClear Function will delete any characters in the
receive buffer for the specified port. After execution, the
receive buffer will be empty.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
Other See SioRxQue.
WSC4VB Reference Manual Page 12
+-------------+-----------------------------------------------------+
| SioRxQue | Returns the number of bytes in the receive queue. |
+-------------+-----------------------------------------------------+
Syntax Function SioRxQue(ByVal Port)
' Port : Port selected.
Remark The SioRxQue Function will return the number of characters in
the receive queue at the time of the call.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
Other See SioRxFlush.
+------------+------------------------------------------------------+
| SioStatus | Returns the serial port status. |
+------------+------------------------------------------------------+
Syntax Function SioStatus(ByVal PortMask)
' Port : Port selected.
' Mask : Error mask.
Remark The SioStatus Function returns the serial port error status
corresponding to the Mask argument.
WSC_RXOVER : The receive queue overflowed.
WSC_OVERRUN : An incoming byte was overwritten.
WSC_PARITY : A parity error was detected (incoming byte)
WSC_FRAME : A framing error was detected (incoming byte)
WSC_BREAK : A break signal was detected.
WSC_TXFULL : The transmit queue is full.
For example, to test for receive queue overflow:
If SioStatus(Port, WSC_RXOVER) > 0 Then
Print "RX Overflow"
End if
The nummerical values of the mask constants are defined in
WSC4VB.PAS.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
WSC4VB Reference Manual Page 13
+------------+------------------------------------------------------+
| SioTxClear | Clears the transmitter buffer. |
+------------+------------------------------------------------------+
Syntax Function SioTxClear(ByVal Port)
' Port : Port selected.
Remark The SioTxClear Function will delete any characters in the
transmit buffer for the specified port.
Once this Function is called, any character in the transmit
buffer (put there by SioPutc) will be lost and therefore not
transmitted.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
Other See SioTxQue & SioTxFlush.
+------------+------------------------------------------------------+
| SioTxQue | Returns the number of bytes in the transmit queue. |
+------------+------------------------------------------------------+
Syntax Function SioTxQue(ByVal Port)
' Port : Port selected.
Remark The SioTxQue Function will return the number of characters in
the transmit queue at the time of the call.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
Other See SioTxFlush.
WSC4VB Reference Manual Page 14
+------------+-----+------------------------------------------------+
| SioUnGetc | .Un|gets. the last character read with SioGetc(). |
+------------+-----+------------------------------------------------+
Syntax Function SioUnGetc(ByVal Port, ByVal Ch)
' Port : Port selected.
' Ch : Character to unget.
Remark The SioUnGetc Function returns (.pushes.) the character back
into the serial input buffer. The character pushed will be
the next character returned by SioGetc. Only one character
can be pushed back. This Function works just like the
.ungetc. Function in the C language.
Return IE_NOPEN : Port not opened. Call SioReset first.
IE_BADID : No such port.
Other See SioReset.
WSC Error Codes
+---------------+---------------------------------------------+
| WSC_NO_DATA | No incoming serial data is available. |
| WSC_RANGE | A parameter is out of range. |
| WSC_ABORTED | The shareware version of WSC corrupted. |
| WSC_WIN32ERR | Win32 system error. |
| WSC_EXPIRED | The shareware version of WSC has expired. |
+---------------+---------------------------------------------+
| IE_BADID | No such port. |
| IE_OPEN | Port already opened. |
| IE_NOPEN | Port not opened. Call SioReset first. |
| IE_MEMORY | Cannot allocate memory for queues. |
| IE_DEFAULT | Error in default parameters. |
| IE_HARDWARE | Hardware not present. |
| IE_BYTESIZE | Unsupported byte size. |
| IE_BAUDRATE | Unsupported baud rate. |
+---------------+---------------------------------------------+
The WSC_EXPIRED error occurs when in the shareware DLL only. It
limits the execution of an WSC DLL to 20 minutes of execution. The
application must be restarted to continue serial processing.
The WSC_ABORTED error occurs in the shareware version only if there
is a problem displaying the shareware screen.
The WSC_WIN32ERR error code is returned only for Win32 system errors.
Call SioError to format the textual error message.
WSC4VB Reference Manual Page 15
+-----------+-------------------------------------------------------+
| mioBreak | Aborts the Modem I/O state driver. |
+-----------+-------------------------------------------------------+
Syntax Function mioBreak(ByVal Port)
' Port : Port selected.
Remark Forces the MIO driver to the IDLE state, abandoning any work
in progress (if any). Used to abort mioSendTo, mioQuiet, and
mioWaitFor functins.
Return MIO_IDLE.
+------------+------------------------------------------------------+
| mioDriver | Modem I/O state driver. |
+------------+------------------------------------------------------+
Syntax Function mioDriver(ByVal Port)
' Port : Port selected.
Remark Executes the next state of any previously started MIO Function
such as mioSendTo, mioWaitFor, and mioQuiet. Returns MIO_IDLE
(defined in MIO.PAS) if ready not running, MIO_RUNNING if
running, and anything else is a character from the modem that
can be displayed if wanted.
Return MIO_IDLE : if the driver is ready for the next mioSendTo,
mioWaitFor, or mioQuiet.
MIO_RUNNING : if the driver is not idle.
<else> : if the driver is not idle, and the returned
character was received from the modem.
WSC4VB Reference Manual Page 16
+-----------+-------------------------------------------------------+
| mioQuiet | Waits for Modem I/O state driver. | *
+-----------+-------------------------------------------------------+
Syntax Function mioQuiet(ByVal Port, ByVal Wait As Long)
' Port : Port selected.
' Wait : Wait in milliseconds.
Remark The mioQuiet Function waits for continuous quiet [no incoming
serial data] of 'Wait' milliseconds before returning. Any
incoming character while mioQuiet is running is lost.
Return TRUE.
+------------+------------------------------------------------------+
| mioResult | Returns result of last mioWaitFor. |
+------------+------------------------------------------------------+
Syntax Function mioResult(ByVal Port)
' Port : Port selected.
Remark The mioResult Function returns the result of the last
mioWaitFor Function. This Function should not be called until
the driver returns MIO_IDLE. See the remarks section of the
mioWaitFor Function for an example.
Return 0 : False (last WaitFor not matched)
!0 : '0' if first substring matched, '1' if second substring
matched, etc.
Other See mioWaitFor.
WSC4VB Reference Manual Page 17
+-----------+-------------------------------------------------------+
| mioSendTo | Sends string to modem. |
+-----------+-------------------------------------------------------+
Syntax Function mioSendTo(ByVal Port, ByVal Pace As Long,
Text As String)
' Port : Port selected.
' Pace : The inter-character delay in milliseconds.
' Text : The string to send.
Remark The mioSendTo Function sends the characters in the string
'Text' to serial output. There is a delay of 'Pace'
milliseconds between characters.
Return TRUE.
+-------------+-----------------------------------------------------+
| mioWaitFor | Waits for continuous quiet. |
+-------------+-----------------------------------------------------+
Syntax Function mioWaitFor(ByVal Port, ByVal Wait As Long,
Text As String)
' Port : Port selected.
' Wait : Total time to wait for response (milliseconds).
' Text : The expected response string.
Remark The mioWaitFor Function waits for characters from serial
input that match the string 'Text'. A total of 'Wait'
milliseconds are allowed before timing out and returning FALSE
(0). The string comparison is NOT case sensitive.
For example, to wait up to one minute for 'CONNECT', 'NO
CARRIER', or 'BUSY' from the modem after dialing a number.
Code = mioWaitFor(ByVal Port,60000,'CONNECT|NO CARRIER|BUSY')
The Function mioDriver() must be called until MIO_IDLE is
returned. Then mioResult() is called to get the result of the
mioWaitFor. A value of 0 indicates that neither 'CONNECT',
'BUSY', nor 'NO CARRIER' was received. A non-zero value
indicates that one of the three sub-strings was received. A
'0' is returned if 'CONNECT' was seen, '1' is returned if 'NO
CARRIER' was seen, and '2' is returned if 'BUSY' was seen.
Return TRUE.
Other See mioResult.
WSC4VB Reference Manual Page 18
+---------+---------------------------------------------------------+
| xyAbort | Aborts the XYDRIVER state driver. |
+---------+---------------------------------------------------------+
Syntax Function xyAbort(ByVal Port)
' Port : Port selected.
Remark The xyAbort Function forces the driver to IDLE, terminating
any file transfer which may be in progress.
Return XY_NO_ERROR (0).
+-----------+-------------------------------------------------------+
| xyAcquire | Prepares the state driver for operation. |
+-----------+-------------------------------------------------------+
Syntax Function xyAcquire(ByVal Port)
' Port : Port selected.
Remark The xyAcquire Function initializes the driver for subsequent
use. This should be the first driver Function called.
Return =0 : No error (XY_NO_ERROR).
<0 : XYDRIVER error. See .XYDRIVER Error Codes.
Other See xyRelease.
WSC4VB Reference Manual Page 19
+----------+--------------------------------------------------------+
| xyDebug | Set the driver debug level. |
+----------+--------------------------------------------------------+
Syntax Function xyDebug(ByVal DebugLevel)
' DebugLevel : Debug level value.
Remark The xyDebug Functions sets the driver debug level as follows:
DebugLevel : Meaning
0 Only error messages are generated [default].
1 Minimal debug messages are generated.
2 Maximal debug messages are generated.
Debug messages are retrieved using the xyGetMessage Function.
Returns New debug level [0,1,2]
+----------+--------------------------------------------------------+
| xyDriver | XMODEM / YMODEM state driver. |
+----------+--------------------------------------------------------+
Syntax Function xyDriver(ByVal Port)
' Port : Port selected.
Return XY_IDLE : A transfer is not underway.
XY_RUNNING : A transfer is underway.
Remark The xyDriver Function drives the state engine. It is normally
called within a timer loop. Note that xyDriver never returns
an error code.
xyDriver can be called as often as wanted whether or not a
file transfer was initiated.
Other See xyStartTx and xyStartRx.
WSC4VB Reference Manual Page 20
+--------------+----------------------------------------------------+
| xyGetMessage | Get next XYDRIVER message. |
+--------------+----------------------------------------------------+
Syntax Function xyGetMessage(Buffer As String, ByVal Size)
' Buffer : Message buffer.
' Size : Size of message buffer.
Remark The xyGetMessage Function retieves the next message from the
driver message queue. Refer to the TERM.C example program for
an example of using xyGetMessage.
Return TRUE : A message was copied into Buffer.
FALSE : No messages are available.
Other See xyDebug.
+----------------+--------------------------------------------------+
| xyGetParameter | Retrieves driver parameter. |
+----------------+--------------------------------------------------+
Syntax Function xyGetParameter(ByVal Port, ByVal Parameter) As Long
' Port : Port Selected.
' Parameter : Parameter to return.
Remark The driver parameter corresponding to the following table is
returned.
Parameter : Desciption
XY_GET_ERROR_CODE : Driver error code (see XYDRIVER.PAS)
XY_GET_ERROR_STATE : Error state (if in error).
XY_GET_PACKET : Current packet number.
XY_GET_STATE : Current state (ss XYDRIVER.C).
XY_GET_FILE_SIZE : File size.
XY_GET_NBR_NAKS : Number of packets ACKed.
XY_GET_LAST_GET : Last incoming (serial) character.
XY_GET_LAST_PUT : Last outgoing (serial) character.
XY_GET_GET_COUNT : Number of incoming characters (bytes).
XY_GET_PUT_COUNT : Number of outgoing characters (bytes).
XY_GET_DRIVER_COUNT : Number times xyDriver() was called.
-1 : Cannot recognize parameter.
The xyGetParameter Function can be used to check the state of
the driver. For example:
(1) xyGetParameter(ByVal Port,XY_GET_STATE) returns XY_IDLE if idle.
(2) xyGetParameter(ByVal Port,XY_GET_ERROR_CODE) returns the driver
error code if an error has occurred or XY_NO_ERROR (0)
otherwise.
Return See above.
WSC4VB Reference Manual Page 21
+-----------+-------------------------------------------------------+
| xyRelease | Releases driver port. |
+-----------+-------------------------------------------------------+
Syntax Function xyRelease(ByVal Port)
' Port : Port selected.
Remark The xyRelease Function releases a port that was previously
acquired with xyAcquire. This Function should be called before
calling the WSC Function SioDone.
Return 0 : No error (XY_NO_ERROR).
<0 : XYDRIVER error. See .XYDRIVER Error Codes.
Other See xyAcquire.
+-----------+-------------------------------------------------------+
| xyStartRx | Start XMODEM or YMODEM receive. |
+-----------+-------------------------------------------------------+
Syntax Function xyStartRx(ByVal Port, Filename As String,
ByVal NCGchar, ByVal Batch)
' Port : Port to use.
' Filename : File to receive (XMODEM only).
' NCGchar : NAK, 'C', or 'G'.
' Batch : YMODEM flag (T/F).
Remark The xyStartRx starts the XMODEM or YMODEM file receive. Once
started, calls to xyDriver are made to execute the next state
(or states). The xyStartTx Function returns immediately.
The protocols supported and their parameters are as follows:
Protocol : NCGchar BatchFlag : Comments
XMODEM : NAK FALSE Standard XMODEM
XMODEM/CRC : 'C' FALSE
XMODEM/1K : 'C' FALSE
YMODEM : 'C' TRUE Standard YMODEM
The xyStart Function is used to receive a file using XMODEM or
YMODEM.
Return =0 : No error (XY_NO_ERROR).
<0 : Driver error. See .XYDRIVER Error Codes. a list of errors.
Other See xyStartTx and xyDriver.
WSC4VB Reference Manual Page 22
+-----------+-------------------------------------------------------+
| xyStartTx | Start XMODEM or YMODEM transmit. |
+-----------+-------------------------------------------------------+
Syntax Function xyStartTx(ByVal Port, Filename As String,
ByVal OneKflag, ByVal Batch)
' Port : Port to use.
' Filename : File to send.
' OneK : Want 1K blocks (T/F).
' Batch : YMODEM flag (T/F).
Remark The xyStartTx starts the XMODEM or YMODEM file send. Once
started, calls to xyDriver are made to execute the next state
(or states). The xyStartTx Function returns immediately.
The protocols supported and their parameters are as follows:
Protocol : OneKflag BatchFlag : Comments
XMODEM : FALSE FALSE Standard XMODEM
XMODEM/CRC : FALSE FALSE
XMODEM/1K : TRUE FALSE
YMODEM : TRUE TRUE Standard YMODEM
Return =0 : No error (XY_NO_ERROR).
<0 : Driver error. See XTDRIVER.PAS for a list of errors.
Other See xyStartRx and xyDriver.
XYDRIVER Error Codes
Error codes are always negative, except for 'no error'. Most of these
error conditions rarely occur. Also note that XYDRIVER Functions can
return WSC errors. An error message is queued when an error occurs
which can be retrieved with xyGetMessage.
The numeric values for error codes can be found in XYDRIVER.PAS.
+--------------------------+----------------------------------------+
| XY_NO_ERROR | No error. (0) |
| XY_UNKNOWN_ERROR | Unknown error. |
| XY_ALREADY_ACTIVE_ERROR | Port already acquired. |
| XY_CANNOT_OPEN_ERROR | Cannot open specifed file. |
| XY_EMPTY_FILE_ERROR | Specified file is empty. |
| XY_NO_STARTUP_CHAR_ERROR | Must specify NAK, 'C', or 'G'. |
| XY_NOT_NCG_ERROR | Expected NAK, 'C', or 'G'. |
| XY_DISK_READ_ERROR | Error reading disk. |
| XY_NO_EOT_ACK_ERROR | EOT was not ACKed. |
| XY_INTERNAL_ERROR | Internal error! |
| XY_CANCELLED_ERROR | Other side cancelled. |
| XY_OUT_OF_SYNC_ERROR | Protocol has lost synchronization. |
| XY_RETRIES_ERROR | Packet retry limit was exceeded. |
| XY_BAD_PACKET_NBR_ERROR | Incorrect packet number. |
| XY_TIMED_OUT_ERROR | Timed out waiting for other side. |
| XY_NO_SUCH_FILE_ERROR | No such file. |
| XY_NOT_ACTIVE_ERROR | Port not acquired by xyAcquire. |
| XY_PORT_RANGE_ERROR | Port number out of range. |
+--------------------------+----------------------------------------+
WSC4VB Reference Manual Page 23
